home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 24 / CU Amiga Magazine's Super CD-ROM 24 (1998)(EMAP Images)(GB)(Track 1 of 2)[!][issue 1998-07].iso / Scalos / RenderLib / doc / autodoc / render.doc < prev    next >
Text File  |  1998-03-06  |  87KB  |  2,472 lines
  1. TABLE OF CONTENTS
  2.  
  3. render.library/AddChunkyImageA
  4. render.library/AddHistogramA
  5. render.library/AddRGB
  6. render.library/AddRGBImageA
  7. render.library/AllocRenderMem
  8. render.library/AllocRenderVec
  9. render.library/AllocRenderVecClear
  10. render.library/ApplyAlphaChannelA
  11. render.library/BestPen
  12. render.library/Chunky2BitMapA
  13. render.library/Chunky2RGBA
  14. render.library/ChunkyArrayDiversityA
  15. render.library/ConvertChunkyA
  16. render.library/CountRGB
  17. render.library/CreateAlphaArrayA
  18. render.library/CreateHistogramA
  19. render.library/CreateMapEngineA
  20. render.library/CreatePaletteA
  21. render.library/CreatePenTableA
  22. render.library/CreateRMHandlerA
  23. render.library/CreateScaleEngineA
  24. render.library/DeleteHistogram
  25. render.library/DeleteMapEngine
  26. render.library/DeletePalette
  27. render.library/DeleteRMHandler
  28. render.library/DeleteScaleEngine
  29. render.library/ExportPaletteA
  30. render.library/ExtractAlphaChannelA
  31. render.library/ExtractPaletteA
  32. render.library/FlushPalette
  33. render.library/FreeRenderMem
  34. render.library/FreeRenderVec
  35. render.library/ImportPaletteA
  36. render.library/InsertAlphaChannelA
  37. render.library/MapChunkyArrayA
  38. render.library/MapRGBArrayA
  39. render.library/MixAlphaChannelA
  40. render.library/MixRGBArrayA
  41. render.library/Planar2ChunkyA
  42. render.library/QueryHistogram
  43. render.library/RenderA
  44. render.library/RGBArrayDiversityA
  45. render.library/ScaleA
  46. render.library/ScaleOrdinate
  47. render.library/SortPaletteA
  48. render.library/TintRGBArrayA
  49. render.library/AddChunkyImageA                 render.library/AddChunkyImageA
  50.  
  51.    NAME
  52.         AddChunkyImageA - add chunky bytes to a histogram.
  53.         AddChunkyImage  - varargs stub for AddChunkyImageA.
  54.  
  55.    SYNOPSIS
  56.         success = AddChunkyImageA(histogram,chunky,width,height,
  57.         d0                        a0        a1     d0    d1     
  58.                                   palette,taglist)
  59.                                   a2      a3
  60.         
  61.         ULONG AddChunkyImageA(APTR,UBYTE *,UWORD,UWORD,
  62.                               APTR,struct TagItem *)
  63.         
  64.         ULONG AddChunkyImage(APTR,UBYTE *,UWORD,UWORD,
  65.                              APTR,tag,...,TAG_DONE)
  66.  
  67.    FUNCTION
  68.         This function adds an array of chunky bytes to a histogram. The
  69.         color information contained in the chunky array and its palette
  70.         will be stored in the histogram.
  71.  
  72.    INPUTS
  73.         histogram       - pointer to a histogram
  74.         chunky          - pointer to an array of chunky bytes
  75.         width           - width to be added [pixels]
  76.         height          - lines to be added [rows]
  77.         palette         - pointer to a palette
  78.                           created with CreatePaletteA()
  79.         taglist         - pointer to an array of TagItems
  80.  
  81.    TAGS
  82.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  83.                 Default - equals to the specified width.
  84.  
  85.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  86.                 structure for progress display operations. Refer to
  87.                 render/renderhooks.h for further information.
  88.                 Default - NULL.
  89.         
  90.    RESULTS
  91.         success - return value to indicate whether the operation succeeded.
  92.                   You must at least check for ADDH_SUCCESS. Adding data to
  93.                   histograms may fail at any time and the histogram may
  94.                   thereof get inaccurate.
  95.  
  96.    NOTES
  97.         - It is not possible with this function to directly add a chunky
  98.           array that represents a HAM color scheme. In this case you have
  99.           to convert it to an RGB array via Chunky2RGBA(), and then to
  100.           call AddRGBImageA().
  101.            
  102.         - This function may call the progress callback Hook with
  103.           the PMSGTYPE_LINES_ADDED message.
  104.         
  105.    SEE ALSO
  106.         AddRGBImageA(), CreateHistogramA(), render/renderhooks.h
  107.  
  108.  
  109. render.library/AddHistogramA                     render.library/AddHistogramA
  110.  
  111.    NAME
  112.         AddHistogramA - add a histogram to another histogram.
  113.         AddHistogram  - varargs stub for AddHistogramA.
  114.  
  115.    SYNOPSIS
  116.         success = AddHistogramA(desthistogram,sourcehistogram,taglist)
  117.         d0                      a0            a1              a2
  118.         
  119.         ULONG AddHistogramA(APTR,APTR,struct TagItem *)
  120.         
  121.         ULONG AddHistogram(APTR,APTR,tag,...,TAG_DONE)
  122.  
  123.    FUNCTION
  124.         This function adds a histogram to another histogram,
  125.         according to the following scheme:
  126.         
  127.         desthistogram + sourcehistogram -> desthistogram
  128.         
  129.         The color information contained in the source histogram
  130.         will be added to the destination histogram.
  131.  
  132.    INPUTS
  133.         desthistogram       - pointer to destination histogram
  134.         sourcehistogram     - pointer to source histogram
  135.         taglist             - pointer to an array of TagItems
  136.  
  137.    TAGS
  138.         RND_Weight (UWORD)  - multiplication factor for the
  139.                 number of representations in sourcehistogram
  140.  
  141.    RESULTS
  142.         success - return value to indicate whether the operation succeeded.
  143.                   You must at least check for ADDH_SUCCESS. Adding data to
  144.                   histograms may fail at any time and the histogram may
  145.                   thereof get inaccurate.
  146.        
  147.    SEE ALSO
  148.         CreateHistogramA()
  149.  
  150.  
  151. render.library/AddRGB                                   render.library/AddRGB
  152.  
  153.    NAME
  154.         AddRGB - add a RGB value to a histogram.
  155.  
  156.    SYNOPSIS
  157.         success = AddRGB(histogram,RGB,count)
  158.         d0               a0        d0  d1
  159.         
  160.         ULONG AddRGB(APTR,ULONG,ULONG)
  161.  
  162.    FUNCTION
  163.         This function adds a given number of representations for a
  164.         single RGB value to a histogram.
  165.  
  166.    INPUTS
  167.         histogram    - pointer to a histogram
  168.         RGB          - RGB value to be added
  169.         count        - number of representations for that RGB value
  170.  
  171.    RESULTS
  172.         success - return value to indicate whether the operation succeeded.
  173.                   You must at least check for ADDH_SUCCESS. Adding data to
  174.                   histograms may fail at any time and the histogram may
  175.                   thereof get inaccurate.
  176.  
  177.    SEE ALSO
  178.         AddRGBImageA(), CreateHistogramA()
  179.  
  180.  
  181. render.library/AddRGBImageA                       render.library/AddRGBImageA
  182.  
  183.    NAME
  184.         AddRGBImageA - add an array of RGB data to a histogram.
  185.         AddRGBImage  - varargs stub for AddRGBImageA.
  186.  
  187.    SYNOPSIS
  188.         success = AddRGBImageA(histogram,rgb,width,height,taglist)
  189.         d0                     a0        a1  d0    d1     a2
  190.         
  191.         ULONG AddRGBImageA(APTR,ULONG *,UWORD,UWORD,struct TagItem *)
  192.         
  193.         ULONG AddRGBImage(APTR,ULONG *,UWORD,UWORD,tag,...,TAG_DONE) 
  194.  
  195.    FUNCTION
  196.         This function adds an array of RGB pixels to a histogram. The
  197.         color information contained in the RGB array gets stored in the
  198.         histogram.
  199.  
  200.    INPUTS
  201.         histogram       - pointer to a histogram
  202.         rgb             - pointer to an array of RGB data
  203.         width           - width to be added [pixels]
  204.         height          - lines to be added [rows]
  205.         taglist         - pointer to an array of TagItems
  206.  
  207.    TAGS
  208.         RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
  209.                 Default - equals to the specified width.
  210.  
  211.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  212.                 structure for progress display operations. Refer to
  213.                 render/renderhooks.h for further information.
  214.                 Default - NULL.
  215.  
  216.    RESULTS
  217.         success - return value to indicate whether the operation succeeded.
  218.                   You must at least check for ADDH_SUCCESS. Adding data to
  219.                   histograms may fail at any time and the histogram may
  220.                   thereof get inaccurate.
  221.  
  222.    NOTES
  223.         - This function may call the progress callback Hook with
  224.           the PMSGTYPE_LINES_ADDED message.
  225.         
  226.    SEE ALSO
  227.         AddRGB(), CreateHistogramA(), render/renderhooks.h
  228.  
  229.  
  230. render.library/AllocRenderMem                   render.library/AllocRenderMem
  231.  
  232.    NAME
  233.         AllocRenderMem - allocate memory from a render-memhandler.
  234.  
  235.    SYNOPSIS
  236.         mem = AllocRenderMem(rendermemhandler,size)
  237.         d0                   a0               d0
  238.  
  239.         APTR AllocRenderMem(APTR, ULONG)
  240.  
  241.    FUNCTION
  242.         AllocRenderMem will allocate a memory block from a
  243.         render-memhandler, or from public memory. If there is no memory
  244.         block of the requested size available, NULL will be returned.
  245.         You must check this return value. The request may fail at any
  246.         time. Every call to this function must be followed by a call to
  247.         FreeRenderMem.
  248.  
  249.    INPUTS
  250.         rendermemhandler - pointer to a render-memhandler, or NULL.
  251.                            If you pass NULL, MEMF_ANY will be used.
  252.         size             - the size of the desired block in bytes
  253.  
  254.    RESULTS
  255.         mem              - pointer to a block of memory, or NULL if the
  256.                            allocation failed.
  257.  
  258.    NOTES
  259.         There is no real need for this function being available to you,
  260.         except for helping you to create a smart, lean and sexy memory
  261.         management - the idea is to enable your application and the
  262.         library to share a particular memory pool.
  263.  
  264.    SEE ALSO
  265.         FreeRenderMem(), AllocRenderVec(), CreateRMHandlerA()
  266.  
  267.  
  268. render.library/AllocRenderVec                   render.library/AllocRenderVec
  269.  
  270.    NAME
  271.         AllocRenderVec - allocate memory from a render-memhandler, 
  272.                          and keep track of the allocated size and
  273.                          the memhandler itself.
  274.  
  275.    SYNOPSIS
  276.         mem = AllocRenderVec(rendermemhandler,size)
  277.         d0                   a0               d0
  278.  
  279.         APTR AllocRenderVec(APTR, ULONG)
  280.  
  281.    FUNCTION
  282.         AllocRenderVec will allocate a memory block from a
  283.         render-memhandler, or from public memory. If there is no memory
  284.         block of the requested size available, NULL will be returned.
  285.         You must check this return value. The request may fail at any
  286.         time. Any call to this function must be followed by a call to
  287.         FreeRenderVec(). AllocRenderVec() keeps track of the allocated
  288.         size and the memhandler itself.
  289.  
  290.    INPUTS
  291.         rendermemhandler - pointer to a render-memhandler, or NULL.
  292.                            If you pass NULL, MEMF_ANY will be used.
  293.         size             - the size of the desired block in bytes
  294.  
  295.    RESULTS
  296.         mem              - pointer to a block of memory, or NULL
  297.                            if the allocation failed.
  298.  
  299.    SEE ALSO
  300.         FreeRenderVec(), AllocRenderVecClear(), AllocRenderMem(),
  301.         CreateRMHandlerA()
  302.  
  303.  
  304. render.library/AllocRenderVecClear         render.library/AllocRenderVecClear
  305.  
  306.    NAME
  307.         AllocRenderVecClear - allocate a clear block of memory from a
  308.                               render-memhandler
  309.  
  310.    SYNOPSIS
  311.         mem = AllocRenderVecClear(rendermemhandler,size)
  312.         d0                        a0               d0
  313.  
  314.         APTR AllocRenderVecClear(APTR, ULONG)
  315.  
  316.    FUNCTION
  317.         AllocRenderVecClear will allocate a clear memory block from a
  318.         render-memhandler, or from public memory. If there is no memory
  319.         block of the requested size available, NULL will be returned.
  320.         You must check this return value. The request may fail at any
  321.         time. Any call to this function must be followed by a call to
  322.         FreeRenderVec(). AllocRenderVecClear() keeps track of the
  323.         allocated size and the memhandler itself.
  324.  
  325.    INPUTS
  326.         rendermemhandler - pointer to a render-memhandler, or NULL.
  327.                            If you pass NULL, MEMF_ANY will be used.
  328.         size             - the size of the desired block in bytes
  329.  
  330.    RESULTS
  331.         mem              - pointer to a block of memory filled with
  332.                            NULL bytes, or NULL if the allocation failed.
  333.  
  334.    SEE ALSO
  335.         FreeRenderVec(), AllocRenderVec(), AllocRenderMem(),
  336.         CreateRMHandlerA()
  337.  
  338.  
  339. render.library/ApplyAlphaChannelA           render.library/ApplyAlphaChannelA
  340.  
  341.    NAME
  342.         ApplyAlphaChannelA - compose RGB array via alpha-channel.
  343.         ApplyAlphaChannel  - varargs stub for ApplyAlphaChannelA.
  344.  
  345.    SYNOPSIS
  346.         ApplyAlphaChannelA(sourcearray,width,height,destarray,tags)
  347.                            a0          d0    d1     a1        a2
  348.  
  349.         void ApplyAlphaChannelA(ULONG *,UWORD,UWORD,ULONG *,
  350.                                 struct TagItem *)
  351.  
  352.         void ApplyAlphaChannel(ULONG *,UWORD,UWORD,ULONG *,
  353.                                tag,...,TAG_DONE)
  354.  
  355.    FUNCTION
  356.         This function uses the alpha-channel information (by default taken
  357.         from the source array) to perform a composition of the source and
  358.         destination array. The result will be written to the
  359.         destination array.
  360.  
  361.    INPUTS
  362.         sourcearray         - pointer to an ARGB array
  363.         width               - width [pixels]
  364.         height              - height [rows]
  365.         destarray           - pointer to a RGB array
  366.         taglist             - pointer to an array of TagItems
  367.  
  368.    TAGS
  369.         RND_SourceWidth (UWORD) - Total width of the source array [pixels].
  370.                 Default - equals to the specified width.
  371.  
  372.         RND_DestWidth (UWORD) - Total width of the dest array [pixels].
  373.                 Default - equals to the specified width.
  374.  
  375.         RND_AlphaChannel (ULONG) - Pointer to the alpha-channel array.
  376.                 Default - equals to the pointer to the source array.
  377.  
  378.         RND_AlphaModulo (UWORD) - Pixel offset that will be used when
  379.                 proceeding from one alpha-channel value to the next [bytes].
  380.                 Default - 4.
  381.  
  382.         RND_AlphaWidth (ULONG) - Total width of the alpha-channel array
  383.                 [pixels]. Default - equals to the specified width.
  384.  
  385.    RESULTS
  386.         none
  387.        
  388.    SEE ALSO
  389.         InsertAlphaChannelA(), ExtractAlphaChannelA(), MixAlphaChannelA()
  390.  
  391.  
  392. render.library/BestPen                                 render.library/BestPen
  393.  
  394.    NAME
  395.         BestPen - find the best matching pen.
  396.  
  397.    SYNOPSIS
  398.         pen = BestPen(palette,RGB)
  399.         d0            a0      d0
  400.         
  401.         LONG BestPen(APTR,ULONG)
  402.  
  403.    FUNCTION
  404.         Determine a palette's pen number that matches best a given RGB
  405.         value.
  406.  
  407.    INPUTS
  408.         palette   - palette created with CreatePaletteA()
  409.         RGB       - RGB value to find a match for
  410.  
  411.    RESULTS
  412.         pen       - pen number or -1 if no pen could be found.
  413.                     (Usually this occurs when the palette is empty.)
  414.  
  415.  
  416. render.library/Chunky2BitMapA                   render.library/Chunky2BitMapA
  417.  
  418.    NAME
  419.         Chunky2BitMapA - convert chunky data to bitplanes.
  420.         Chunky2BitMap  - varargs stub for Chunky2BitMapA.
  421.  
  422.    SYNOPSIS
  423.         Chunky2BitMapA(chunky,sx,sy,width,height,bitmap,dx,dy,taglist)
  424.                        a0     d0 d1 d2    d3     a1     d4 d5 a2
  425.         
  426.         void Chunky2BitMapA(UBYTE *,UWORD,UWORD,UWORD,UWORD,
  427.                             struct BitMap *,UWORD,UWORD,struct TagItem *)
  428.         
  429.         void Chunky2BitMap(UBYTE *,UWORD,UWORD,UWORD,UWORD,
  430.                            struct BitMap *,UWORD,UWORD,tag,...,TAG_DONE) 
  431.  
  432.    FUNCTION
  433.         Converts an array of chunky bytes to the bitplanes associated
  434.         with a BitMap structure. You can specify clip areas both inside
  435.         the chunky array and the BitMap. This function merges the data
  436.         into the destination BitMap if required. BMF_INTERLEAVED is also
  437.         handled.
  438.         
  439.         You may only process BMF_STANDARD bitmaps with this function.
  440.  
  441.    INPUTS
  442.         chunky     - pointer to an array of chunky bytes
  443.         sx         - left edge inside the chunky array [pixels]
  444.         sy         - top edge inside the chunky array [rows]
  445.         width      - width [pixels]
  446.         height     - height [rows]
  447.         bitmap     - pointer to an initialized BitMap structure
  448.         dx         - destination left edge inside BitMap [pixels]
  449.         dy         - destination top edge inside BitMap [rows]
  450.         taglist    - pointer to an array of TagItems
  451.  
  452.    TAGS
  453.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  454.                 Default - equals to the specified width.
  455.  
  456.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  457.                 for a secondary conversion of the pen numbers.
  458.                 Default - NULL.
  459.  
  460.    RESULTS
  461.         none
  462.  
  463.    IMPORTANT NOTES
  464.         Starting with v39, you are not allowed to assume foreign BitMap
  465.         structures being of a planar type. You may pass a BitMap
  466.         structure to this function only if the BMF_STANDARD flag is set.
  467.  
  468.         Also remember to set-up your own BitMap structure with the
  469.         BMF_STANDARD flag if you wish to convert it with this function.
  470.         Consider Chunky2BitMapA() being low-level. The BitMap structure
  471.         involved here is intended to hold planar information. Since v39,
  472.         this is different to what graphics.library might associate with
  473.         a BitMap structure.
  474.  
  475.         Do not use this function with BitMap structures that are
  476.         actually being displayed. If you wish to transfer chunky bytes
  477.         to visible areas, use graphics.library functions, such as
  478.         WriteChunkyPixels(), or WritePixelArray8(). You may also use
  479.         Chunky2BitMapA() followed by BltBitMapRastPort() etc.
  480.  
  481.         With a graphics card supplied, WriteChunkyPixels() can be
  482.         hundereds times faster than Chunky2BitMapA() followed by
  483.         BltBitMapRastPort(). If you have to provide backward
  484.         compatibility, it is worth the effort to differenciate between
  485.         Kick 2.x and OS 3.x. Use Chunky2BitMapA() in the first case,
  486.         WritePixelArray8() in the second case, and WriteChunkyPixels()
  487.         if the system runs under OS3.1 and is supplied with a graphics
  488.         card.
  489.  
  490. SEE ALSO
  491.         Planar2ChunkyA(), graphics/gfx.h,
  492.         graphics.library/WriteChunkyPixels()
  493.  
  494.  
  495. render.library/Chunky2RGBA                         render.library/Chunky2RGBA
  496.  
  497.    NAME
  498.         Chunky2RGBA - convert an array of chunky bytes to RGB data.
  499.         Chunky2RGB  - varargs stub for Chunky2RGBA.
  500.  
  501.    SYNOPSIS
  502.         success = Chunky2RGBA(chunky,width,height,rgb,palette,taglist)
  503.         d0                    a0     d0    d1     a1  a2      a3
  504.         
  505.         ULONG Chunky2RGBA(UBYTE *,UWORD,UWORD,ULONG *,APTR,struct TagItem *)
  506.         
  507.         ULONG Chunky2RGB(UBYTE *,UWORD,UWORD,ULONG *,APTR,tag,...,TAG_DONE) 
  508.  
  509.    FUNCTION
  510.         This function converts an array of chunky bytes to RGB data.
  511.  
  512.    INPUTS
  513.         chunky      - pointer to an array of chunky bytes
  514.         width       - width to be converted [pixels]
  515.         height      - height to be converted [rows]
  516.         rgb         - pointer to RGB destination buffer
  517.         palette     - pointer to a palette created
  518.                       with CreatePaletteA()
  519.         taglist     - pointer to an array of TagItems
  520.  
  521.    TAGS
  522.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  523.                 Default - equals to the specified width.
  524.  
  525.         RND_DestWidth (UWORD) - Total width of the RGB array [pixels].
  526.                 Default - equals to the specified width.
  527.  
  528.         RND_ColorMode (ULONG) - Color mode that defines how to determine
  529.                 a pixel's actual color. Valid types:
  530.  
  531.                 COLORMODE_CLUT          - normal palette lookup
  532.                 COLORMODE_HAM8          - HAM8 mode palette lookup
  533.                 COLORMODE_HAM6          - HAM6 mode palette lookup
  534.                 
  535.                 Default - COLORMODE_CLUT.
  536.  
  537.         RND_LeftEdge (UWORD) - Horizontal starting position inside the
  538.                 chunky array [pixels]. This is mainly intended to allow
  539.                 the conversion of HAM clip areas.
  540.                 Default - 0.
  541.  
  542.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  543.                 structure for progress display operations. Refer to
  544.                 render/renderhooks.h for further information.
  545.                 Default - NULL.
  546.  
  547.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  548.                 for an additional conversion of the pen numbers.
  549.                 Default - NULL.
  550.                 Note: This is not defined for HAM modes.
  551.  
  552.         RND_LineHook (ULONG) - Pointer to a callback hook structure
  553.                 for line-related operations during conversion. This
  554.                 hook is executed once before a line is processed and
  555.                 once after it has been completed. Refer to
  556.                 render/renderhooks.h for further information.
  557.                 Default - NULL.
  558.  
  559.    RESULTS
  560.         success - CONV_SUCCESS to indicate that the operation
  561.                   succeeded. Currently, the only reason for this
  562.                   function to fail is CONV_CALLBACK_ABORTED.
  563.  
  564.    NOTES
  565.         - This function may call the progress callback Hook
  566.           with the PMSGTYPE_LINES_CONVERTED message type.
  567.  
  568.    SEE ALSO
  569.         render/render.h
  570.  
  571.  
  572. render.library/ChunkyArrayDiversityA     render.library/ChunkyArrayDiversityA
  573.  
  574.    NAME
  575.         ChunkyArrayDiversityA - calculate chunky array adaptibility
  576.         ChunkyArrayDiversity  - varargs stub for ChunkyArrayDiversityA.
  577.  
  578.    SYNOPSIS
  579.         diversity = ChunkyArrayDiversityA(chunkyarray,palette,
  580.         d0                                a0          a1
  581.                                           width,height,taglist)
  582.                                           d0    d1     a2
  583.  
  584.         LONG ChunkyArrayDiversityA(UBYTE *,APTR,UWORD,UWORD,
  585.                                    struct TagItem *)
  586.  
  587.         LONG ChunkyArrayDiversity(UBYTE *,UWORD,UWORD,
  588.                                   tag,...,TAG_DONE)
  589.  
  590.    FUNCTION
  591.         Calculate a chunky array's adaptibility to a palette or
  592.         mapping-engine.
  593.  
  594.    INPUTS
  595.         chunkyarray - pointer to an array of chunky bytes
  596.         palette     - the chunky array's palette
  597.         width       - width to be processed [pixels]
  598.         height      - height to be processed [pixels]
  599.         taglist     - pointer to an array of tagitems
  600.  
  601.    TAGS
  602.         RND_Palette (ULONG) - pointer to a palette. Either this or the
  603.                 RND_MapEngine argument is obligatory!
  604.  
  605.         RND_MapEngine (ULONG) - pointer to a mapping-engine. Either this
  606.                 or the RND_Palette argument is obligatory!
  607.  
  608.         RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
  609.                 Default - equals to the specified width.
  610.  
  611.         RND_Interleave (ULONG) - number of pixels to skip horizontally.
  612.                 Default - 0.
  613.  
  614.    RESULTS
  615.         diversity - an indicator for the chunky array's adaptibility
  616.                     to the given palette or mapping-engine. 0 indicates
  617.                     perfect adaptibility, 195075 indicates the worst case.
  618.  
  619.    IMPLEMENTATION   
  620.         Every color in the source array is adapted to the specified
  621.         palette or mapping-engine. Now assume p2 is the RGB of the
  622.         palette entry that matches best with the requested color p1.
  623.  
  624.             R
  625.             |
  626.             |      * p2
  627.             |     /
  628.             |    /
  629.             |   / d
  630.             |__/_________G
  631.            /  /
  632.           /  * p1
  633.          /
  634.         B
  635.  
  636.         This function sums up the diversity d² for every color in the
  637.         source array, and divides it by the number of pixels processed:
  638.  
  639.                           k=pixels
  640.                   1         ___
  641.         D   =   ------   .  \\  `   d(k)²
  642.                 pixels      /__,
  643.  
  644.                              k=1
  645.  
  646.         D is returned, so what you get is the average d² for all RGB
  647.         values that appear in the array. d² is summed up instead of d
  648.         because it is a better indicator for most purposes.
  649.  
  650.         Best case - all pixels match perfectly: D(min) = 0.
  651.         Worst case - all pixels are white, and the only available color
  652.         in the palette is black: D(max) = 255²+255²+255² = 195075.
  653.         
  654.    EXAMPLE        
  655.         D indicates a palette's applicability for the given chunky
  656.         array. You can e.g. use it to decide whether error diffusion
  657.         should be enabled for ConvertChunkyA().
  658.  
  659.         dithermode = DITHERMODE_NONE;
  660.  
  661.         D = ChunkyArrayDiversity(sourcearray, palette, width, height, 
  662.             RND_Palette, destpalette, RND_Interleave, 4, TAG_DONE);
  663.  
  664.         if (D > threshold)
  665.         {
  666.             dithermode = DITHERMODE_FS;
  667.         }
  668.  
  669.         ConvertChunky(sourcearray, palette, width, height, destarray,
  670.             destpalette, RND_DitherMode, dithermode, TAG_DONE);
  671.  
  672.         The interleave factor increases speed drastically. You gain a
  673.         lot of performance if only dithering can be avoided sometimes.
  674.  
  675.    SEE ALSO
  676.         RGBArrayDiversityA()
  677.  
  678.  
  679. render.library/ConvertChunkyA                   render.library/ConvertChunkyA
  680.  
  681.    NAME
  682.         ConvertChunkyA - convert an array of chunky bytes to a new palette.
  683.         ConvertChunky  - varargs stub for ConvertChunkyA.
  684.  
  685.    SYNOPSIS
  686.         success = ConvertChunkyA(source,sourcepalette,width,height,dest,        
  687.         d0                       a0     a1            d0    d1     a2   
  688.                                  destpalette,taglist)
  689.                                  a3          a4
  690.         
  691.         ULONG ConvertChunkyA(UBYTE *,APTR,UWORD,UWORD,UBYTE *,
  692.                              APTR,struct TagItem *)
  693.         
  694.         ULONG ConvertChunky(UBYTE *,APTR,UWORD,UWORD,UBYTE *,
  695.                             APTR,tag,...,TAG_DONE)
  696.  
  697.    FUNCTION
  698.         This function converts a source array of chunky bytes to another
  699.         chunky array, and adapts it to a new palette.
  700.  
  701.    INPUTS
  702.         source        - pointer to a source array of chunky bytes
  703.         sourcepalette - pointer to the source array's palette
  704.         width         - width to be converted [pixels]
  705.         height        - height to be converted [rows]
  706.         dest          - pointer to the destination chunky array
  707.         destpalette   - pointer to the destination array's palette
  708.         taglist       - pointer to an array of TagItems
  709.  
  710.    TAGS
  711.         RND_SourceWidth (UWORD) - Total width of source array [pixels].
  712.                 Default - equals to the specified width.
  713.  
  714.         RND_DestWidth (UWORD) - Total width of dest array [pixels].
  715.                 Default - equals to the specified width.
  716.  
  717.         RND_DitherMode (UWORD) - Error diffusion mode. Valid types:
  718.  
  719.                 DITHERMODE_NONE   - no error diffusion
  720.  
  721.                 DITHERMODE_FS     - Floyd-Steinberg
  722.                                     Does not handle a dither amount.
  723.  
  724.                 DITHERMODE_RANDOM - Random dithering
  725.                                     Handles RND_DitherAmount.
  726.  
  727.                 DITHERMODE_EDD    - EDD dithering
  728.                                     Does not handle a dither amount.
  729.  
  730.                 Default - DITHERMODE_NONE.
  731.  
  732.         RND_DitherAmount (UWORD) - Dither intensity (0-255).
  733.                 Only valid with certain dither modes (see above).
  734.                 Default - 128.
  735.  
  736.         RND_LineHook (ULONG) - Pointer to a callback hook structure
  737.                 for line-related operations during conversion. This
  738.                 hook is executed once before a line is rendered and
  739.                 once after a line has been completed. Refer to
  740.                 render/renderhooks.h for further information.
  741.                 Default - NULL.
  742.  
  743.         RND_OffsetColorZero (UWORD) - First pen number to appear
  744.                 in the rendered chunky image. This offset will be
  745.                 added to the palette's indices. Default - 0.
  746.                 Note: RND_PenTable overrides RND_OffsetColorZero.
  747.  
  748.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  749.                 for a secondary conversion of the pen numbers.
  750.                 Default - NULL.
  751.                 Note: RND_PenTable overrides RND_OffsetColorZero.
  752.  
  753.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  754.                 structure for progress display operations. Refer to
  755.                 render/renderhooks.h for further information.
  756.                 Default - NULL.
  757.  
  758.         RND_ScaleEngine (ULONG) - Pointer to a scaling-engine.
  759.                 This scaling-engine will be used to scale the
  760.                 source data stream before it is being rendered.
  761.                 Default - NULL.
  762.  
  763.                 Notes: 
  764.                 - The scaling engine's destination width and
  765.                   height specifications override the width and
  766.                   height arguments for RenderA().
  767.                 - The scaling-engine must have been created with
  768.                   PIXFMT_CHUNKY_CLUT.
  769.  
  770.         RND_MapEngine (ULONG) - Pointer to a mapping-engine.
  771.                 This can greatly improve performance.
  772.                 Default - NULL.
  773.                 
  774.                 Notes:
  775.                 - The mapping-engine must have been created for
  776.                   the destination palette that is specified for
  777.                   ConvertChunkyA().
  778.                 - With dithering enabled, you better do not
  779.                   specify a mapping-engine which was created with
  780.                   a link to a histogram. Accurate conversion could
  781.                   not be guaranteed in this case.
  782.  
  783.    RESULTS
  784.         success - returncode to indicate whether the operation
  785.                   succeeded. You must at least check for
  786.                   CONV_SUCCESS.
  787.  
  788.    NOTES
  789.         - This function may call the progress callback Hook with
  790.           the PMSGTYPE_LINES_CONVERTED message type.
  791.         
  792.    SEE ALSO
  793.         MapChunkyArrayA(), RenderA(), CreatePenTableA(),
  794.         CreatePaletteA(), render/render.h, render/renderhooks.h
  795.  
  796.  
  797. render.library/CountRGB                               render.library/CountRGB
  798.  
  799.    NAME
  800.         CountRGB     - count a RGB value in a histogram.
  801.  
  802.    SYNOPSIS
  803.         count = CountRGB(histogram,RGB)
  804.         d0               a0        d0
  805.         
  806.         ULONG CountRGB(APTR,ULONG)
  807.  
  808.    FUNCTION
  809.         Counts the number of occurances for a given RGB value. The
  810.         result may depend on the histogram's accuracy.
  811.  
  812.    INPUTS
  813.         histogram - pointer to a histogram
  814.  
  815.    RESULTS
  816.         count     - number of representations for the
  817.                     specified RGB value.
  818.  
  819.    NOTE
  820.         You only get the exact result for 24bit histograms. The lower
  821.         the resolution, the more colors are actually put together into
  822.         one `category' of similar colors. A 24bit histogram
  823.         differenciates 16,7 million colors, a 15bit histogram, for
  824.         instance, only 32768.
  825.  
  826.  
  827. render.library/CreateAlphaArrayA             render.library/CreateAlphaArrayA
  828.  
  829.    NAME
  830.         CreateAlphaArrayA - create an alpha-channel for a RGB array.
  831.         CreateAlphaArray  - varargs stub for CreateAlphaArrayA.
  832.  
  833.    SYNOPSIS
  834.         CreateAlphaArrayA(rgbarray,width,height,tags)
  835.                           a0       d0    d1     a1
  836.  
  837.         void CreateAlphaArrayA(ULONG *,UWORD,UWORD,struct TagItem *)
  838.  
  839.         void CreateAlphaArray(ULONG *,UWORD,UWORD,tag,...,TAG_DONE)
  840.  
  841.    FUNCTION
  842.         This function creates an alpha-channel for the given RGB array.
  843.         The alpha-channel will be the difference in brightness towards
  844.         black (0x000000), or optionally towards another RGB value.
  845.  
  846.    INPUTS
  847.         rgbarray            - pointer to a RGB array
  848.         width               - width [pixels]
  849.         height              - height [rows]
  850.         taglist             - pointer to an array of TagItems
  851.  
  852.    TAGS
  853.         RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
  854.                 Default - equals to the specified width.
  855.  
  856.         RND_AlphaChannel (ULONG) - Alpha-channel destination array.
  857.                 Default - equals to rgbarray. the upmost byte in the
  858.                 RGB array is a good place for an alpha-channel, usually.
  859.  
  860.         RND_AlphaWidth (UWORD) - Total width of the alpha-channel array
  861.                 [pixels]. Default - equals to the specified width.
  862.  
  863.         RND_AlphaModulo (UWORD) - Alpha-channel pixel modulo [bytes].
  864.                 Default - 4
  865.                 
  866.         RND_MaskRGB (ULONG) - The RGB value to compute the alpha-channel
  867.                 towards. Default - 0x000000
  868.  
  869.    RESULTS
  870.         none
  871.  
  872.  
  873. render.library/CreateHistogramA               render.library/CreateHistogramA
  874.  
  875.    NAME
  876.         CreateHistogramA - create and set up a histogram.
  877.         CreateHistogram  - varargs stub for CreateHistogramA.
  878.  
  879.    SYNOPSIS
  880.         hst = CreateHistogramA(taglist)
  881.         d0                     a1
  882.         
  883.         APTR CreateHistogramA(struct TagItem *)
  884.         
  885.         APTR CreateHistogram(tag,...,TAG_DONE)
  886.  
  887.    FUNCTION
  888.         Allocates and initializes a histogram.
  889.  
  890.    INPUTS
  891.         taglist - pointer to an array of TagItems
  892.  
  893.    TAGS
  894.         RND_RMHandler (ULONG) - pointer to a render-memhandler
  895.                 created with CreateRMHandlerA().
  896.                 Default - NULL.
  897.  
  898.         RND_HSType (UWORD) - Type of histogram. Valid types:
  899.  
  900.                 HSTYPE_12BIT            - 12bit dynamic histogram
  901.                 HSTYPE_15BIT            - 15bit dynamic histogram
  902.                 HSTYPE_18BIT            - 18bit dynamic histogram
  903.                 HSTYPE_21BIT            - 21bit dynamic histogram
  904.                 HSTYPE_24BIT            - 24bit dynamic histogram
  905.                 HSTYPE_12BIT_TURBO      - 12bit tabular histogram
  906.                 HSTYPE_15BIT_TURBO      - 15bit tabular histogram
  907.                 HSTYPE_18BIT_TURBO      - 18bit tabular histogram
  908.  
  909.                 Default - HSTYPE_15BIT_TURBO.
  910.  
  911.    RESULTS
  912.         histogram - pointer to a histogram ready for usage,
  913.                     or NULL if something went wrong.
  914.  
  915.    SEE ALSO
  916.         DeleteHistogram(), QueryHistogram(), render/render.h
  917.  
  918.  
  919. render.library/CreateMapEngineA               render.library/CreateMapEngineA
  920.  
  921.    NAME
  922.         CreateMapEngineA - create a mapping-engine.
  923.         CreateMapEngine - varargs stub for CreateMappingEngineA.
  924.  
  925.    SYNOPSIS
  926.         engine = CreateMapEngineA(palette,taglist)
  927.         d0                        a0       a1
  928.  
  929.         ULONG CreateMapEngineA(APTR,struct TagItem *)
  930.         
  931.         ULONG CreateMapEngine(APTR,tag,...,TAG_DONE)
  932.  
  933.   FUNCTION
  934.         This function will create and prepare a mapping-engine for
  935.         usage. Mapping-engines are highly optimized low-level conversion
  936.         units for rendering to a specific palette.
  937.  
  938.         Mapping-engines are immediately dependent from a palette, and
  939.         they may be additionally coupled with a histogram. In the latter
  940.         case, mapping-engines adapt only RGB values that can be found in
  941.         the histogram.
  942.  
  943.         Mapping-engines do not incorporate the contents of their
  944.         palettes and histograms. They are getting notified, and they
  945.         automagically update themselves when needed. This update takes
  946.         place only on demand, i.e. whenever you pass a mapping-engine to
  947.         a function. The mapping-engine checks if any changes applied to
  948.         the palette or histogram, and it reconstructs itself. The
  949.         palette's pen-adaption buffers are updated as well - palettes
  950.         and mapping-engines are just good friends.
  951.  
  952.    INPUTS
  953.         palette       - pointer to a palette
  954.         taglist       - pointer to an array of TagItems
  955.  
  956.    TAGS
  957.         RND_RMHandler (ULONG) - Pointer to a render-memhandler.
  958.                 This will be used for the mapping-engine's
  959.                 buffers. Default - The palette's memhandler.
  960.    
  961.         RND_Histogram (ULONG) - Pointer to a histogram.
  962.                 The histogram must be of a HSTYPE_..._TURBO type,
  963.                 and have the same resolution as the palette.
  964.                 Default - none.
  965.  
  966.    RESULTS
  967.         engine - pointer to a mapping-engine ready for usage,
  968.                  or NULL if something went wrong.
  969.  
  970.    NOTES
  971.         You must free a mapping-engine before you DeletePalette() the
  972.         palette it is dependent from. The same applies for the
  973.         histogram.
  974.  
  975.    SEE ALSO
  976.         DeleteMapEngine(), MapRGBArrayA(), CreateRMHandlerA()
  977.  
  978.  
  979. render.library/CreatePaletteA                   render.library/CreatePaletteA
  980.  
  981.    NAME
  982.         CreatePaletteA - create a palette.
  983.         CreatePalette  - vararg stub for CreatePaletteA.
  984.  
  985.    SYNOPSIS
  986.         palette = CreatePaletteA(taglist)
  987.         d0                       a1
  988.         
  989.         APTR CreatePaletteA(struct TagItem *)
  990.         
  991.         APTR CreatePalette(tag,...,TAG_DONE)
  992.  
  993.    FUNCTION
  994.         This function creates and initializes a palette that can hold up
  995.         to 256 color entries.
  996.  
  997.    INPUTS
  998.         taglist     - pointer to an array of TagItems
  999.  
  1000.    TAGS
  1001.         RND_HSType (ULONG) - the palette's resolution. Palette adaption
  1002.                 accuracy and memory consumption depend on this constant.
  1003.                 A palette's resolution is specified analogously to a
  1004.                 histogram's resolution. Valid types:
  1005.  
  1006.                 HSTYPE_12BIT
  1007.                 HSTYPE_15BIT
  1008.                 HSTYPE_18BIT
  1009.  
  1010.                 Default - HSTYPE_15BIT.
  1011.  
  1012.         RND_RMHandler (ULONG) - pointer to a render-memhandler that was
  1013.                 created with CreateRMHandler(). Default - NULL.
  1014.         
  1015.    RESULTS
  1016.         palette  - a palette ready for usage,
  1017.                    or NULL if something went wrong.
  1018.  
  1019.    SEE ALSO
  1020.         DeletePalette(), ImportPaletteA(), ExportPaletteA(), 
  1021.         ExtractPaletteA(), FlushPalette(), render/render.h
  1022.  
  1023.  
  1024. render.library/CreatePenTableA                 render.library/CreatePenTableA
  1025.  
  1026.    NAME
  1027.         CreatePenTableA - create a pen conversion table.
  1028.         CreatePenTable  - varargs stub for CreatePenTableA.
  1029.  
  1030.    SYNOPSIS
  1031.         CreatePenTableA(chunky,oldpalette,width,height,newpalette,
  1032.                         a0     a1         d0    d1     a2
  1033.                         pentab,taglist)
  1034.                         a3     a4
  1035.         
  1036.         void CreatePenTableA(UBYTE *,APTR,UWORD,UWORD,APTR,
  1037.                              UBYTE *,struct TagItem *)
  1038.         
  1039.         void CreatePenTable(UBYTE *,APTR,UWORD,UWORD,APTR,
  1040.                             UBYTE *,tag,...,TAG_DONE)
  1041.  
  1042.    FUNCTION
  1043.         This function creates a table for the conversion of a particular
  1044.         array of chunky bytes. It scans through the chunky array, adapts
  1045.         the found palette entries to a new palette, and generates an
  1046.         output table of 256 UBYTEs. The resulting table is handled as
  1047.         follows:
  1048.  
  1049.         new_pen_number = pentab[old_pen_number]
  1050.         
  1051.    INPUTS
  1052.         chunky      - pointer to an array of chunky bytes
  1053.         oldpalette  - pointer to the original palette
  1054.         width       - width to be processed [pixels]
  1055.         height      - height to be processed [rows]
  1056.         newpalette  - pointer to a palette to be adapted to
  1057.         pentab      - pointer to the destination table
  1058.         taglist     - pointer to an array of TagItems
  1059.  
  1060.    TAGS
  1061.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  1062.                 Default - equals to the specified width.
  1063.  
  1064.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  1065.                 for a secondary conversion of the pen numbers.
  1066.                 Default - NULL.
  1067.         
  1068.    RESULTS
  1069.         none
  1070.         
  1071.    NOTES
  1072.         The destination table is assumed to have 256 entries,
  1073.         with no respect to what color indices actually occur in
  1074.         the chunky array.
  1075.  
  1076.    SEE ALSO
  1077.         ConvertChunkyA(), CreatePaletteA()
  1078.  
  1079.  
  1080. render.library/CreateRMHandlerA               render.library/CreateRMHandlerA
  1081.  
  1082.    NAME
  1083.         CreateRMHandlerA - Create and set up a memory handler.
  1084.         CreateRMHandler  - varargs stub for CreateRMHandlerA.
  1085.  
  1086.    SYNOPSIS
  1087.         rmh = CreateRMHandlerA(taglist)
  1088.         d0                     a1
  1089.         
  1090.         APTR CreateRMHandlerA(struct TagItem *)
  1091.         
  1092.         APTR CreateRMHandler(tag,...,TAG_DONE)
  1093.  
  1094.    FUNCTION
  1095.         This function allocates and initializes a render-memhandler.
  1096.         This is a custom memory resource manager for histograms,
  1097.         rendering, palettes, and many other render.library
  1098.         objects and functions. You may use a render-memhandler for your
  1099.         own purposes, too.
  1100.  
  1101.         A render-memhandler helps to avoid memory fragmentation as well
  1102.         as extreme stressing of the system's public memory lists.
  1103.         Private memory management is supported as well as v39 exec pools
  1104.         and common public memory. Future versions might provide more
  1105.         types of memory management.
  1106.  
  1107.    INPUTS
  1108.         taglist - pointer to an array of TagItems
  1109.  
  1110.    TAGS
  1111.         RND_MemType (UWORD) - type of memory management. Valid types:
  1112.  
  1113.                 RMHTYPE_POOL            - v39 exec dynamic pool
  1114.                 RMHTYPE_PRIVATE         - you supply a private memory pool
  1115.                 RMHTYPE_PUBLIC          - use common public memory
  1116.  
  1117.                 Default - RMHTYPE_PUBLIC.
  1118.  
  1119.         RND_MemBlock (ULONG) - pointer to a block of memory
  1120.                 used for private memory management. This tag
  1121.                 is obligatory if you specify RMHTYPE_PRIVATE
  1122.                 and is ignored otherwise. 
  1123.                 Default - none.
  1124.  
  1125.         RND_MemSize (ULONG) - size of the memory block used
  1126.                 for private memory management. This tag is
  1127.                 obligatory if you specify RMHTYPE_PRIVATE
  1128.                 and is ignored otherwise. 
  1129.                 Default - none.
  1130.  
  1131.         RND_MemFlags (ULONG) - memory flags, as defined in
  1132.                 exec/memory.h. These are ignored for
  1133.                 RMHTYPE_PRIVATE. Default - MEMF_ANY.
  1134.  
  1135.    RESULTS
  1136.         rmh - a render-memhandler ready for usage, or NULL if
  1137.               something went wrong.
  1138.  
  1139.    NOTES
  1140.         You must check for the presence of exec v39 before you create a
  1141.         memhandler with RMHTYPE_POOL specified.
  1142.  
  1143.    SEE ALSO
  1144.         AllocRenderMem(), AllocRenderVec(), DeleteRMHandler(),
  1145.         exec.library/CreatePool(), render/render.h, exec/memory.h
  1146.  
  1147.  
  1148. render.library/CreateScaleEngineA           render.library/CreateScaleEngineA
  1149.  
  1150.    NAME
  1151.         CreateScaleEngineA - Create a scaling-engine.
  1152.         CreateScaleEngine  - varargs stub for CreateScaleEngineA.
  1153.  
  1154.    SYNOPSIS
  1155.         scaleengine = CreateScaleEngineA(sourcewidth,sourceheight,
  1156.         d0                               d0          d1           
  1157.                                          destwidth,destheight,taglist)
  1158.                                          d2        d3         a1
  1159.         
  1160.         APTR CreateScaleEngineA(UWORD,UWORD,UWORD,
  1161.                                 UWORD,struct TagItem *)
  1162.         
  1163.         APTR CreateScaleEngine(UWORD,UWORD,UWORD,
  1164.                                UWORD,tag,...,TAG_DONE)
  1165.  
  1166.    FUNCTION
  1167.         Allocates and initializes a scaling-engine for a specific set of
  1168.         scaling parameters. Once set up, a scaling-engine is highly
  1169.         optimized for its particular parameter specifications.
  1170.  
  1171.    INPUTS
  1172.         sourcewidth  - source width [pixels]
  1173.         sourceheight - source height [rows]
  1174.         destwidth    - destination width [pixels]
  1175.         destheight   - destination height [rows]
  1176.         taglist      - pointer to an array of tag items
  1177.  
  1178.    TAGS
  1179.         RND_RMHandler (ULONG) - pointer to a render-memhandler,
  1180.                 such as created with CreateRMHandlerA().
  1181.                 Default - NULL.
  1182.  
  1183.         RND_PixelFormat (ULONG) - Type of data to process.
  1184.                 Currently defined are PIXFMT_CHUNKY_CLUT
  1185.                 and PIXFMT_0RGB_32. Default - PIXFMT_CHUNKY_CLUT.
  1186.  
  1187.         RND_Coordinates (ULONG) - Pointer to an array of coordinates
  1188.                 for texturemapped scaling. This array consists of
  1189.                 4 WORD pairs of x/y coordinates each. The array forms
  1190.                 a trapezoid inside the destination buffer for the source
  1191.                 array being mapped to. Any parameters are valid, since
  1192.                 clipping is fully implemented. Default - NULL.
  1193.  
  1194.    RESULTS
  1195.         engine - a scaling-engine ready for usage, or NULL
  1196.                  if something went wrong.
  1197.  
  1198.    SEE ALSO
  1199.         DeleteScaleEngine(), ScaleA()
  1200.  
  1201.  
  1202. render.library/DeleteHistogram                 render.library/DeleteHistogram
  1203.  
  1204.    NAME
  1205.         DeleteHistogram - dispose a histogram.
  1206.  
  1207.    SYNOPSIS
  1208.         DeleteHistogram(histogram)
  1209.                         a0
  1210.  
  1211.         void DeleteHistogram(APTR)
  1212.  
  1213.    FUNCTION
  1214.         Removes a histogram and frees all associated memory.
  1215.  
  1216.    INPUTS
  1217.         histogram   - pointer to a histogram
  1218.                       Passing a NULL pointer is safe.
  1219.  
  1220.    RESULTS
  1221.         none
  1222.  
  1223.  
  1224. render.library/DeleteMapEngine                 render.library/DeleteMapEngine
  1225.  
  1226.    NAME
  1227.         DeleteMapEngine - dispose a mapping-engine.
  1228.  
  1229.    SYNOPSIS
  1230.         DeleteMapEngine(engine)
  1231.                         a0
  1232.  
  1233.         void DeleteMapEngine(APTR)
  1234.  
  1235.    FUNCTION
  1236.         Removes a mapping-engine and frees all associated memory.
  1237.  
  1238.    INPUTS
  1239.         engine   - pointer to a mapping-engine
  1240.  
  1241.    NOTES
  1242.         You must free mapping-engines before you delete the
  1243.         palettes and histograms they're dependent from.
  1244.  
  1245.    RESULTS
  1246.         none
  1247.  
  1248.    SEE ALSO
  1249.         CreateMapEngine()
  1250.  
  1251.  
  1252. render.library/DeleteRMHandler                 render.library/DeleteRMHandler
  1253.  
  1254.    NAME
  1255.         DeleteRMHandler - free a render-memhandler.
  1256.  
  1257.    SYNOPSIS
  1258.         DeleteRMHandler(rendermemhandler)
  1259.                         a0
  1260.  
  1261.         void DeleteRMHandler(APTR)
  1262.  
  1263.    FUNCTION
  1264.         DeleteRMHandler() will remove and free a previously created
  1265.         render-memhandler. That does not imply that any outstanding
  1266.         memory will be returned to the system or to whatever memory
  1267.         ressources. You are responsible for freeing each memory block
  1268.         that you have allocated from a render-memhandler.
  1269.  
  1270.    INPUTS
  1271.         render-memhandler - a render-memhandler to be deleted.
  1272.  
  1273.    RESULTS
  1274.         none
  1275.  
  1276.    NOTES
  1277.         You are not allowed to call DeleteRMHandler() before every
  1278.         single byte has been returned to the memhandler.
  1279.  
  1280.    SEE ALSO
  1281.         CreateRMHandlerA()
  1282.  
  1283.  
  1284. render.library/DeletePalette                     render.library/DeletePalette
  1285.  
  1286.    NAME
  1287.         DeletePalette - dispose a palette.
  1288.  
  1289.    SYNOPSIS
  1290.         DeletePalette(palette)
  1291.                       a0
  1292.  
  1293.         void DeletePalette(APTR)
  1294.  
  1295.    FUNCTION
  1296.         This function deletes a palette and frees all
  1297.         associated memory.
  1298.  
  1299.    INPUTS
  1300.         palette   - pointer to a palette created
  1301.                     with CreatePaletteA()
  1302.  
  1303.    RESULTS
  1304.         none
  1305.  
  1306.    SEE ALSO
  1307.         CreatePaletteA(), FlushPalette()
  1308.  
  1309.  
  1310. render.library/DeleteScaleEngine             render.library/DeleteScaleEngine
  1311.  
  1312.    NAME
  1313.         DeleteScaleEngine - dispose a scaling-engine.
  1314.  
  1315.    SYNOPSIS
  1316.         DeleteScaleEngine(engine)
  1317.                           a0
  1318.  
  1319.         void DeleteScaleEngine(APTR)
  1320.  
  1321.    FUNCTION
  1322.         Deletes a scaling-engine and frees all associated memory.
  1323.  
  1324.    INPUTS
  1325.         engine   - a scaling-engine to be removed
  1326.  
  1327.    RESULTS
  1328.         none
  1329.  
  1330.    SEE ALSO
  1331.         CreateScaleEngineA()
  1332.  
  1333.  
  1334. render.library/ExportPaletteA                   render.library/ExportPaletteA
  1335.  
  1336.    NAME
  1337.         ExportPaletteA - export a palette.
  1338.         ExportPalette  - varargs stub for ExportPaletteA.
  1339.  
  1340.    SYNOPSIS
  1341.         ExportPaletteA(palette,buffer,taglist)
  1342.                        a0      a1     a2
  1343.         
  1344.         ExportPaletteA(APTR,APTR,struct TagItem *)
  1345.         
  1346.         ExportPalette(APTR,APTR,tag,...,TAG_DONE)
  1347.  
  1348.    FUNCTION
  1349.         This function exports a palette (or a part of it)
  1350.         to a colortable.
  1351.  
  1352.    INPUTS
  1353.         palette   - pointer to a palette created
  1354.                     with CreatePaletteA()
  1355.         buffer    - pointer to a destination buffer
  1356.         taglist   - pointer to an array of tag items
  1357.  
  1358.    TAGS
  1359.         RND_PaletteFormat (ULONG) - format of the color table
  1360.                 to be exported. Valid types:
  1361.  
  1362.                 PALFMT_RGB32    - ULONG red,green,blue
  1363.                 PALFMT_RGB8     - ULONG 0x00rrggbb
  1364.                 PALFMT_RGB4     - UWORD 0xrgb
  1365.  
  1366.                 Default - PALFMT_RGB8.
  1367.  
  1368.         RND_FirstColor (ULONG) - first color entry to export.
  1369.                 Default - 0.
  1370.         
  1371.         RND_NumColors (ULONG) - number of colors to export.
  1372.                 Default - the number of colors inside the palette.
  1373.  
  1374.    RESULTS
  1375.         none
  1376.  
  1377.    SEE ALSO
  1378.         CreatePaletteA(), ImportPaletteA()
  1379.  
  1380.  
  1381. render.library/ExtractAlphaChannelA       render.library/ExtractAlphaChannelA
  1382.  
  1383.    NAME
  1384.         ExtractAlphaChannelA - extract alpha-channel from an ARGB array.
  1385.         ExtractAlphaChannel  - varargs stub for ExtractAlphaChannelA.
  1386.  
  1387.    SYNOPSIS
  1388.         ExtractAlphaChannelA(argbarray,width,height,chunkyarray,tags)
  1389.                              a0       d0    d1     a1          a2
  1390.  
  1391.         void ExtractAlphaChannelA(ULONG *,UWORD,UWORD,UBYTE *,
  1392.                                   struct TagItem *)
  1393.  
  1394.         void ExtractAlphaChannel(ULONG *,UWORD,UWORD,UBYTE *,
  1395.                                  tag,...,TAG_DONE)
  1396.  
  1397.    FUNCTION
  1398.         This function extracts the alpha-channel mask from an ARGB array
  1399.         and writes it to an array of chunky bytes.
  1400.  
  1401.    INPUTS
  1402.         argbarray           - pointer to an ARGB array
  1403.         width               - width [pixels]
  1404.         height              - height [rows]
  1405.         chunkyarray         - pointer to an array of chunky bytes
  1406.         taglist             - pointer to an array of TagItems
  1407.  
  1408.    TAGS
  1409.         RND_SourceWidth (UWORD) - Total width of the ARGB array [pixels].
  1410.                 Default - equals to the specified width.
  1411.  
  1412.         RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
  1413.                 Default - equals to the specified width.
  1414.  
  1415.    RESULTS
  1416.         none
  1417.        
  1418.    SEE ALSO
  1419.         InsertAlphaChannelA(), ApplyAlphaChannelA()
  1420.  
  1421.  
  1422. render.library/ExtractPaletteA                 render.library/ExtractPaletteA
  1423.  
  1424.    NAME
  1425.         ExtractPaletteA - extract a palette from a histogram.
  1426.         ExtractPalette  - varargs stub for ExtractPaletteA.
  1427.  
  1428.    SYNOPSIS
  1429.         success = ExtractPaletteA(histogram,palette,numcolors,taglist)
  1430.         d0                        a0        a1      d0        a2
  1431.         
  1432.         ULONG ExtractPaletteA(APTR,ULONG *,UWORD,struct TagItem *)
  1433.         
  1434.         ULONG ExtractPalettA(APTR,ULONG *,UWORD,tag,...,TAG_DONE)
  1435.  
  1436.    FUNCTION
  1437.         This function extracts a given number of colors from a
  1438.         histogram and stores it in a palette.
  1439.  
  1440.    INPUTS
  1441.         histogram - pointer to a histogram
  1442.         palette   - pointer to a palette created
  1443.                     with CreatePaletteA()
  1444.         numcolors - number of entries to extract
  1445.         taglist   - pointer to an array of TagItems
  1446.  
  1447.    TAGS
  1448.         RND_RMHandler (ULONG) - Custom memory handler created with
  1449.                 CreateRMHandlerA(). This is used to handle intermediate
  1450.                 buffers during quantization.
  1451.                 Default - The histogram's memory handler.
  1452.  
  1453.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  1454.                 structure for progress display operations. Refer to
  1455.                 render/renderhooks.h for further information.
  1456.                 Default - NULL.
  1457.  
  1458.         RND_RGBWeight (ULONG) - R/G/B quantization factors.
  1459.                 They form a relative measurement between the R/G/B
  1460.                 components, defining what color components should be
  1461.                 preferred when the histogram gets decomposed.
  1462.                 Default - 0x010101 (all components are treat equally).
  1463.  
  1464.         RND_ColorMode (ULONG) - Color mode that defines how to determine
  1465.                 a pixel's actual color. Currently this tag should only be
  1466.                 set to COLORMODE_HAM6 if you extract a palette for the
  1467.                 use with a HAM6 image. 
  1468.                 Default - COLORMODE_CLUT.
  1469.  
  1470.         RND_FirstColor (ULONG) - first color entry inside the palette
  1471.                 that will be used for the extracted colors. See also
  1472.                 ImportPaletteA() for further details. Default - 0.
  1473.  
  1474.         RND_NewPalette (ULONG) - if set to TRUE, this flag indicates
  1475.                 that you want to dispose the current palette and
  1476.                 create a new one. If set to FALSE, the new color entries
  1477.                 are merged to the existing palette. Default - TRUE.
  1478.  
  1479.    RESULTS
  1480.         success - returncode to indicate whether the operation
  1481.                   succeeded. You must at least check for
  1482.                   EXTP_SUCCESS.
  1483.  
  1484.    NOTES
  1485.         - This function may call the progress callback Hook
  1486.           with the PMSGTYPE_COLORS_CHOSEN message type.
  1487.  
  1488.    SEE ALSO
  1489.         CreateHistogramA(), CreatePaletteA(), ImportPaletteA(),
  1490.         render/render.h, render/renderhooks.h
  1491.  
  1492.  
  1493. render.library/FlushPalette                       render.library/FlushPalette
  1494.  
  1495.    NAME
  1496.         FlushPalette - flush all buffers from a palette.
  1497.  
  1498.    SYNOPSIS
  1499.         FlushPalette(palette)
  1500.                      a0
  1501.  
  1502.         void FlushPalette(APTR)
  1503.  
  1504.    FUNCTION
  1505.         This function flushes all buffers that might be
  1506.         associated with a palette.
  1507.  
  1508.    INPUTS
  1509.         palette   - pointer to a palette that was
  1510.                     created with CreatePaletteA()
  1511.  
  1512.    RESULTS
  1513.         none
  1514.  
  1515.    SEE ALSO
  1516.         DeletePalette()
  1517.  
  1518.  
  1519. render.library/FreeRenderMem                     render.library/FreeRenderMem
  1520.  
  1521.    NAME
  1522.         FreeRenderMem - return memory to a render-memhandler.
  1523.  
  1524.    SYNOPSIS
  1525.         FreeRenderMem(rendermemhandler,mem,size)
  1526.                       a0               a1  d0
  1527.  
  1528.         void FreeRenderMem(APTR,APTR,ULONG)
  1529.  
  1530.    FUNCTION
  1531.         Free a block of memory that was allocated with
  1532.         AllocRenderMem().
  1533.  
  1534.    INPUTS
  1535.         rendermemhandler - pointer to the render-memhandler the block
  1536.                            has been allocated from
  1537.         mem              - pointer to the memory block to be returned
  1538.         size             - size of that memory block [bytes]
  1539.  
  1540.    RESULTS
  1541.         NONE
  1542.  
  1543.    SEE ALSO
  1544.         AllocRenderMem(), CreateRMHandlerA()
  1545.  
  1546.  
  1547. render.library/FreeRenderVec                     render.library/FreeRenderVec
  1548.  
  1549.    NAME
  1550.         FreeRenderVec - return memory to a render-memhandler.
  1551.  
  1552.    SYNOPSIS
  1553.         FreeRenderVec(mem)
  1554.                       a0
  1555.  
  1556.         void FreeRenderVec(APTR)
  1557.  
  1558.    FUNCTION
  1559.         Free a block of memory that was allocated with AllocRenderVec().
  1560.  
  1561.    INPUTS
  1562.         mem - pointer to a memory block
  1563.               to be returned to its render-memhandler.
  1564.               Passing a NULL pointer is safe.
  1565.  
  1566.    RESULTS
  1567.         NONE
  1568.  
  1569.    SEE ALSO
  1570.         AllocRenderVec(), DeleteRMHandler()
  1571.  
  1572.  
  1573. render.library/ImportPaletteA                   render.library/ImportPaletteA
  1574.  
  1575.    NAME
  1576.         ImportPaletteA - import a palette.
  1577.         ImportPalette  - varargs stub for ImportPaletteA.
  1578.  
  1579.    SYNOPSIS
  1580.         ImportPaletteA(palette,table,entries,taglist)
  1581.                        a0      a1    d0      a2
  1582.         
  1583.         ImportPaletteA(APTR,APTR,UWORD,struct TagItem *)
  1584.         
  1585.         ImportPalette(APTR,APTR,UWORD,tag,...,TAG_DONE)
  1586.         
  1587.    FUNCTION
  1588.         This function imports entries from a color table (or from a
  1589.         palette) to a palette. You are allowed to import multiple times.
  1590.         When doing so, entries will be overwritten (not inserted). The
  1591.         palette automatically grows to the required number of entries.
  1592.         Remember to neither import more than 256 entries nor beyond the
  1593.         256th entry.
  1594.  
  1595.    INPUTS
  1596.         palette   - pointer to a palette created
  1597.                     with CreatePaletteA()
  1598.         table     - pointer to a source color table
  1599.                     (or a render.library palette)
  1600.         entries   - number of color entries to import
  1601.         taglist   - pointer to an array of tag items
  1602.  
  1603.    TAGS
  1604.         RND_PaletteFormat (ULONG) - format of the color table
  1605.                 to be imported. Valid types:
  1606.  
  1607.                 PALFMT_RGB32    - ULONG red,green,blue
  1608.                 PALFMT_RGB8     - ULONG 0x00rrggbb
  1609.                 PALFMT_RGB4     - UWORD 0xrgb
  1610.                 PALFMT_PALETTE  - another palette
  1611.  
  1612.                 Default - PALFMT_RGB8.
  1613.  
  1614.         RND_FirstColor (ULONG) - first color entry inside the
  1615.                 palette to import to. Default - 0.
  1616.  
  1617.         RND_EHBPalette (ULONG) - tag to indicate whether the
  1618.                 imported colors should be interpreted as for an
  1619.                 Extra-Halfbrite picture. Default - FALSE.
  1620.  
  1621.         RND_NewPalette (ULONG) - if set to TRUE, this flag indicates
  1622.                 that you want to dispose the current palette and
  1623.                 import a new one. If set to FALSE, the palette is
  1624.                 merged. Default - TRUE.
  1625.  
  1626.    RESULTS
  1627.         none
  1628.  
  1629.    SEE ALSO
  1630.         CreatePaletteA(), ExportPaletteA(), render/render.h
  1631.  
  1632.  
  1633. render.library/InsertAlphaChannelA         render.library/InsertAlphaChannelA
  1634.  
  1635.    NAME
  1636.         InsertAlphaChannelA - insert a alpha-channel mask to a RGB array.
  1637.         InsertAlphaChannel  - varargs stub for InsertAlphaChannelA.
  1638.  
  1639.    SYNOPSIS
  1640.         InsertAlphaChannelA(chunkyarray,width,height,rgbarray,tags)
  1641.                             a0          d0    d1     a1       a2
  1642.  
  1643.         void InsertAlphaChannelA(UBYTE *,UWORD,UWORD,ULONG *,
  1644.                                  struct TagItem *)
  1645.  
  1646.         void InsertAlphaChannel(UBYTE *,UWORD,UWORD,ULONG *,
  1647.                                 tag,...,TAG_DONE)
  1648.  
  1649.    FUNCTION
  1650.         This function inserts an array of chunky bytes to a RGB array.
  1651.         The resulting ARGB array can then be used for alpha-channel
  1652.         operations, such as provided with ApplyAlphaChannelA().
  1653.  
  1654.    INPUTS
  1655.         chunkyarray         - pointer to an array of chunky bytes
  1656.         width               - width [pixels]
  1657.         height              - height [rows]
  1658.         rgbarray            - pointer to a RGB array
  1659.         taglist             - pointer to an array of TagItems
  1660.  
  1661.    TAGS
  1662.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  1663.                 Default - equals to the specified width.
  1664.  
  1665.         RND_DestWidth (UWORD) - Total width of the rgb array [pixels].
  1666.                 Default - equals to the specified width.
  1667.  
  1668.    RESULTS
  1669.         none
  1670.        
  1671.    SEE ALSO
  1672.         ExtractAlphaChannelA(), ApplyAlphaChannelA()
  1673.  
  1674.  
  1675. render.library/MapChunkyArrayA                 render.library/MapChunkyArrayA
  1676.  
  1677.    NAME
  1678.         MapChunkyArrayA - remap a chunky array.
  1679.         MapChunkyArray  - varargs stub for MapChunkyArrayA.
  1680.  
  1681.    SYNOPSIS
  1682.         success = MapChunkyArrayA(engine,sourcearray,palette,width,
  1683.         d0                        a0     a1          a2      d0    
  1684.                                   height,destarray,taglist)
  1685.                                   d1     a3        a4
  1686.  
  1687.         ULONG MapChunkyArrayA(APTR,UBYTE *,APTR,UWORD,UWORD,UBYTE *,
  1688.                               struct TagItem *)
  1689.  
  1690.         ULONG MapChunkyArray(APTR,UBYTE *,APTR,UWORD,UWORD,UBYTE *,
  1691.                              tag,...,TAG_DONE)
  1692.  
  1693.    FUNCTION
  1694.         MapChunkyArrayA() maps an array of chunky bytes to another
  1695.         chunky array.
  1696.  
  1697.    INPUTS
  1698.         engine      - pointer to a mapping-engine created
  1699.                       with CreateMapEngineA()
  1700.         sourcearray - pointer to source array of chunky pixels
  1701.         palette     - pointer to source array's palette
  1702.         width       - width to be converted [pixels]
  1703.         height      - height to be converted [rows]
  1704.         destarray   - pointer to the destination chunky array
  1705.         taglist     - pointer to an array of TagItems
  1706.  
  1707.    TAGS
  1708.         RND_SourceWidth (UWORD) - Total width of the chunky array [pixels].
  1709.                 Default - equals to the specified width.
  1710.  
  1711.         RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
  1712.                 Default - equals to the specified width.
  1713.  
  1714.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  1715.                 for a secondary conversion of the pen numbers.
  1716.                 Default - NULL.
  1717.  
  1718.    RESULTS
  1719.         success - returncode to indicate whether the operation
  1720.                   succeeded. You must at least check for
  1721.                   CONV_SUCCESS.
  1722.  
  1723.    NOTES
  1724.         This function is considered low-level. Much more functionality
  1725.         is provided with ConvertChunkyA(). Mapping-engines may also be
  1726.         passed to ConvertChunkyA(), and MapChunkyArrayA() is only slightly
  1727.         faster in this case. ConvertChunkyA() is preferable under most
  1728.         circumstances. If you need to remap lots of tiny images, you
  1729.         might prefer MapChunkyArrayA(), since it has got very few overhead.
  1730.  
  1731.    SEE ALSO
  1732.         ConvertChunkyA(), MapRGBArrayA(), CreateMapEngineA()
  1733.  
  1734.  
  1735. render.library/MapRGBArrayA                       render.library/MapRGBArrayA
  1736.  
  1737.    NAME
  1738.         MapRGBArrayA - map an RGB array to chunky bytes.
  1739.         MapRGBArray  - varargs stub for MapRGBArrayA.
  1740.  
  1741.    SYNOPSIS
  1742.         success = MapRGBArrayA(engine,rgbarray,width,height,chunky,taglist)
  1743.         d0                     a0     a1       d0    d1     a2     a3
  1744.  
  1745.         ULONG MapRGBArrayA(APTR,ULONG *,UWORD,UWORD,UBYTE *,struct TagItem *)
  1746.  
  1747.         ULONG MapRGBArray(APTR,ULONG *,UWORD,UWORD,UBYTE *,tag,...,TAG_DONE)
  1748.  
  1749.    FUNCTION
  1750.         MapRGBArrayA() maps an array of RGB data to a chunky array.
  1751.  
  1752.    INPUTS
  1753.         engine      - pointer to a mapping-engine created
  1754.                       with CreateMapEngineA()
  1755.         rgbarray    - pointer to an array of RGB pixels
  1756.         width       - width to be converted [pixels]
  1757.         height      - height to be converted [rows]
  1758.         chunky      - pointer to the destination array
  1759.         taglist     - pointer to an array of TagItems
  1760.  
  1761.    TAGS
  1762.         RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
  1763.                 Default - equals to the specified width.
  1764.  
  1765.         RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
  1766.                 Default - equals to the specified width.
  1767.  
  1768.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  1769.                 for a secondary conversion of the pen numbers.
  1770.                 Default - NULL.
  1771.  
  1772.    RESULTS
  1773.         success - returncode to indicate whether the operation
  1774.                   succeeded. You must at least check for
  1775.                   CONV_SUCCESS.
  1776.  
  1777.    NOTES
  1778.         - Do not use MapRGBArrayA() with ARGB (A=alpha-channel) data.
  1779.           The upper byte must be set to zero!
  1780.         - This function is considered low-level. Much more functionality
  1781.           is provided with RenderA(). Mapping-engines may also be passed
  1782.           to RenderA(), and MapRGBArrayA() is only slightly faster in this
  1783.           case. RenderA() is preferable under most circumstances. If you
  1784.           need to render lots of tiny images, you might prefer
  1785.           MapRGBArrayA(), since it has got few overhead.
  1786.  
  1787.    SEE ALSO
  1788.         RenderA(), MapChunkyArrayA(), CreateMapEngineA()
  1789.  
  1790.  
  1791. render.library/MixAlphaChannelA               render.library/MixAlphaChannelA
  1792.  
  1793.    NAME
  1794.         MixAlphachannelA - mix two arrays via alpha-channels.
  1795.         MixAlphachannel  - varargs stub for MixAlphachannelA.
  1796.  
  1797.    SYNOPSIS
  1798.         MixAlphachannelA(sourcearray1,sourcearray2,width,height,destarray,
  1799.                          a0           a1           d0    d1     a2
  1800.                          tags)
  1801.                          a3
  1802.  
  1803.         void MixAlphachannelA(ULONG *,ULONG *,UWORD,UWORD,ULONG *,
  1804.                               struct TagItem *)
  1805.  
  1806.         void MixAlphachannel(ULONG *,ULONG*,UWORD,UWORD,ULONG *,
  1807.                              tag,...,TAG_DONE)
  1808.  
  1809.    FUNCTION
  1810.         This function does a 'weighted' alpha-channel composition of
  1811.         two RGB arrays and writes the result to a third RGB array.
  1812.         You may optionally disable one or both alpha-channel sources,
  1813.         in the latter case a 1:1 mix (without alpha-channel) will be
  1814.         performed.
  1815.  
  1816.    INPUTS
  1817.         sourcearray1        - pointer to an RGB array, source
  1818.         sourcearray2        - pointer to an RGB array, source
  1819.         width               - width [pixels]
  1820.         height              - height [rows]
  1821.         destarray           - pointer to an RGB array, destination
  1822.         taglist             - pointer to an array of TagItems
  1823.  
  1824.    TAGS
  1825.         RND_SourceWidth (UWORD) - Total width of sourcearray1 [pixels].
  1826.                 Default - equals to the specified width.
  1827.  
  1828.         RND_SourceWidth2 (UWORD) - Total width of sourcearray2 [pixels].
  1829.                 Default - equals to the specified width.
  1830.  
  1831.         RND_DestWidth (UWORD) - Total width of destarray [pixels].
  1832.                 Default - equals to the specified width.
  1833.  
  1834.         RND_AlphaChannel (ULONG) - Pointer to an alpha-channel array
  1835.                 for sourcearray1. This may be NULL. Default - equals
  1836.                 to sourcearray1.
  1837.        
  1838.         RND_AlphaWidth (UWORD) - Total width of the first alpha-channel
  1839.                 array [pixels]. Default - equals to RND_SourceWidth.
  1840.  
  1841.         RND_AlphaModulo (UWORD) - Alpha-channel pixel modulo for the
  1842.                 first alpha-channel array [bytes]. Default - 4
  1843.  
  1844.         RND_AlphaChannel2 (ULONG) - Pointer to an alpha-channel array
  1845.                 for sourcearray2. This may be NULL. Default - equals
  1846.                 to sourcearray2.
  1847.  
  1848.         RND_AlphaWidth2 (UWORD) - Total width of the second alpha-channel
  1849.                 array [pixels]. Default - equals to RND_SourceWidth2.
  1850.  
  1851.         RND_AlphaModulo2 (UWORD) - Alpha-channel pixel modulo for the
  1852.                 second alpha-channel array [bytes]. Default - 4
  1853.                 
  1854.    RESULTS
  1855.         none
  1856.  
  1857.    NOTES
  1858.         this function is much more generalized than ApplyAlphaChannelA()
  1859.         and MixRGBArrayA(), but it has got more overhead and might be
  1860.         noticably slower. read the appropriate autodoc sections to see
  1861.         if one of the above mentioned functions suffice for your particular
  1862.         purpose.
  1863.  
  1864.    SEE ALSO
  1865.         ApplyAlphaChannelA(), MixRGBArrayA(), InsertAlphaChannelA(),
  1866.         ExtractAlphaChannelA()
  1867.  
  1868.  
  1869. render.library/MixRGBArrayA                       render.library/MixRGBArrayA
  1870.  
  1871.    NAME
  1872.         MixRGBArrayA - mix two RGB arrays.
  1873.         MixRGBArray  - varargs stub for MixRGBArrayA.
  1874.  
  1875.    SYNOPSIS
  1876.         MixRGBArrayA(sourcearray,width,height,destarray,ratio,tags)
  1877.                      a0          d0    d1     a1        d2    a2
  1878.  
  1879.         void MixRGBArrayA(ULONG *,UWORD,UWORD,ULONG *,UWORD,
  1880.                           struct TagItem *)
  1881.  
  1882.         void MixRGBArray(ULONG *,UWORD,UWORD,ULONG *,UWORD,
  1883.                          tag,...,TAG_DONE)
  1884.  
  1885.    FUNCTION
  1886.         This function mixes sourcearray and destarray and writes
  1887.         the result to destarray. Unlike ApplyAlphaChannelA(), this
  1888.         function does not use any alpha-channel information.
  1889.  
  1890.    INPUTS
  1891.         sourcearray         - pointer to an ARGB array
  1892.         width               - width [pixels]
  1893.         height              - height [rows]
  1894.         destarray           - pointer to a RGB array
  1895.         ratio               - mix ratio (0...255)
  1896.         taglist             - pointer to an array of TagItems
  1897.  
  1898.    TAGS
  1899.         RND_SourceWidth (UWORD) - Total width of the source array [pixels].
  1900.                 Default - equals to the specified width.
  1901.  
  1902.         RND_DestWidth (UWORD) - Total width of the dest array [pixels].
  1903.                 Default - equals to the specified width.
  1904.  
  1905.    RESULTS
  1906.         none
  1907.        
  1908.    SEE ALSO
  1909.         ApplyAlphaChannelA()
  1910.  
  1911.  
  1912. render.library/Planar2ChunkyA                   render.library/Planar2ChunkyA
  1913.  
  1914.    NAME
  1915.         Planar2ChunkyA - convert bitplane data to chunky bytes.
  1916.         Planar2Chunky  - varargs stub for Planar2ChunkyA.
  1917.  
  1918.    SYNOPSIS
  1919.         Planar2ChunkyA(planetab,bytewidth,rows,depth,bytesperrow,
  1920.                        a0       d0        d1   d2    d3
  1921.                        chunkybuffer,taglist)
  1922.                        a1           a2
  1923.  
  1924.         void Planar2ChunkyA(PLANEPTR *,UWORD,UWORD,UWORD,UWORD,
  1925.                             UBYTE *,struct TagItem *)
  1926.         
  1927.         void Planar2Chunky(PLANEPTR *,UWORD,UWORD,UWORD,UWORD
  1928.                             UBYTE *,tag,...,TAG_DONE)
  1929.  
  1930.    FUNCTION
  1931.         This function converts raw bitplane-oriented (planar) graphics
  1932.         to an array of chunky bytes.
  1933.  
  1934.    INPUTS
  1935.         planetab    - pointer to a table of planepointers
  1936.         bytewidth   - width [bytes]. This must be an even number.
  1937.         rows        - height [rows]
  1938.         depth       - number of bitplanes in planetab
  1939.         bytesperrow - total bytes per row in the source bitplanes.
  1940.                       This must be an even number. If you convert
  1941.                       interleaved bitplanes, multiply by depth.
  1942.         chunky      - pointer to the destination chunky buffer
  1943.         taglist     - pointer to an array of TagItems
  1944.  
  1945.    TAGS
  1946.         RND_DestWidth (UWORD) - Total width of chunky array [pixels].
  1947.                 Default - equals to bytewidth * 8.
  1948.  
  1949.                 You are explicitely allowed to use a destwidth that is
  1950.                 smaller than bytewidth * 8 pixels.
  1951.                 
  1952.                 Important note:
  1953.                 If you specify this tag, you must _still_ supply a
  1954.                 chunky buffer of at least bytewidth * 8 * rows bytes.
  1955.  
  1956.    NOTES
  1957.         Starting with v39, you are not allowed to assume foreign BitMap
  1958.         structures being of a planar type. Before you grab a table of
  1959.         planepointers out of an unknown BitMap structure and pass it to
  1960.         this function, you have to check for the presence of the
  1961.         BMF_STANDARD flag.
  1962.  
  1963.    RESULTS
  1964.         none
  1965.  
  1966.    SEE ALSO
  1967.         Chunky2BitMapA(), graphics/gfx.h
  1968.  
  1969.  
  1970. render.library/QueryHistogram                   render.library/QueryHistogram
  1971.  
  1972.    NAME
  1973.         QueryHistogram - query a histogram parameter.
  1974.  
  1975.    SYNOPSIS
  1976.         value = QueryHistogram(histogram,tag)
  1977.         d0                     a0        d0
  1978.         
  1979.         ULONG QueryHistogram(APTR,Tag)
  1980.  
  1981.    FUNCTION
  1982.         Query one of a histogram's specifications
  1983.         via Tag parameter.
  1984.  
  1985.    INPUTS
  1986.         histogram - pointer to a histogram
  1987.         tag       - Tag to be queried
  1988.  
  1989.    TAGS
  1990.         RND_NumColors (ULONG) -
  1991.                 the number of different colors inside the histogram
  1992.  
  1993.         RND_NumPixels (ULONG) -
  1994.                 the number of pixels that have been added to the
  1995.                 histogram
  1996.  
  1997.         RND_RMHandler (ULONG) -
  1998.                 the histogram's render-memhandler
  1999.  
  2000.         RND_HSType (UWORD) -
  2001.                 the histogram's type
  2002.  
  2003.    RESULTS
  2004.         value    - the queried parameter
  2005.  
  2006.    SEE ALSO
  2007.         CreateHistogramA()
  2008.  
  2009.  
  2010. render.library/RenderA                                 render.library/RenderA
  2011.  
  2012.    NAME
  2013.         RenderA - render an array of RGB data to chunky bytes.
  2014.         Render  - varargs stub for RenderA.
  2015.  
  2016.    SYNOPSIS
  2017.         success = RenderA(rgb,width,height,chunky,palette,taglist)
  2018.         d0                a0  d0    d1     a1     a2      a3
  2019.         
  2020.         ULONG RenderA(ULONG *,UWORD,UWORD,UBYTE *,APTR,struct TagItem *)
  2021.         
  2022.         ULONG Render(ULONG *,UWORD,UWORD,UBYTE *,APTR,tag,...,TAG_DONE)
  2023.  
  2024.    FUNCTION
  2025.         Render an array of RGB data to an array of chunky bytes.
  2026.  
  2027.    INPUTS
  2028.         rgb         - pointer to an array of RGB pixels
  2029.         width       - width to be converted [pixels]
  2030.         height      - height to be converted [rows]
  2031.         chunky      - pointer to the destination array
  2032.         palette     - pointer to a palette to be rendered to
  2033.         taglist     - pointer to an array of TagItems
  2034.  
  2035.    TAGS
  2036.         RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
  2037.                 Default - equals to the specified width.
  2038.  
  2039.         RND_DestWidth (UWORD) - Total width of the chunky array [pixels].
  2040.                 Default - equals to the specified width.
  2041.  
  2042.         RND_ColorMode (ULONG) - Color mode that defines how to determine
  2043.                 a pixel's actual color. Valid types:
  2044.  
  2045.                 COLORMODE_CLUT          - normal palette lookup
  2046.                 COLORMODE_HAM8          - HAM8 mode palette lookup
  2047.                 COLORMODE_HAM6          - HAM6 mode palette lookup
  2048.                 
  2049.                 Default - COLORMODE_CLUT.
  2050.  
  2051.         RND_DitherMode (UWORD) - Error diffusion mode. Valid types:
  2052.  
  2053.                 DITHERMODE_NONE   - no error diffusion
  2054.  
  2055.                 DITHERMODE_FS     - Floyd-Steinberg
  2056.                                     Does not handle a dither amount.
  2057.  
  2058.                 DITHERMODE_RANDOM - Random dithering
  2059.                                     Handles RND_DitherAmount.
  2060.  
  2061.                 DITHERMODE_EDD    - EDD dithering
  2062.                                     Does not handle a dither amount.
  2063.  
  2064.                 Default - DITHERMODE_NONE.
  2065.  
  2066.         RND_ProgressHook (ULONG) - Pointer to a callback hook
  2067.                 structure for progress display operations. Refer to
  2068.                 render/renderhooks.h for further information.
  2069.                 Default - NULL.
  2070.  
  2071.         RND_OffsetColorZero (UWORD) - First pen number to appear
  2072.                 in the rendered chunky image. This offset will be
  2073.                 added to the palette's indices. Default - 0.
  2074.                 Note: RND_PenTable overrides RND_OffsetColorZero.
  2075.  
  2076.         RND_PenTable (ULONG) - Pointer to a table of 256 UBYTEs
  2077.                 for a secondary conversion of the pen numbers.
  2078.                 Default - NULL.
  2079.                 Note: RND_PenTable overrides RND_OffsetColorZero.
  2080.  
  2081.         RND_LineHook (ULONG) - Pointer to a callback hook structure
  2082.                 for line-related operations during render. This hook
  2083.                 is executed once before a line is rendered and once
  2084.                 after it has been completed. Refer to
  2085.                 render/renderhooks.h for further information.
  2086.                 Default - NULL.
  2087.  
  2088.         RND_DitherAmount (UWORD) - Dither intensity (0-255).
  2089.                 Only valid with certain dither modes (see above).
  2090.                 Default - 128.
  2091.  
  2092.         RND_ScaleEngine (ULONG) - Pointer to a scaling-engine.
  2093.                 This scaling-engine will be used to scale the
  2094.                 source data stream before it is being rendered.
  2095.                 Default - NULL.
  2096.  
  2097.                 Notes: 
  2098.                 - The scaling engine's destination width and
  2099.                   height specifications override the width and
  2100.                   height arguments for RenderA().
  2101.                 - The scaling-engine must have been created with
  2102.                   PIXFMT_0RGB_32.
  2103.  
  2104.         RND_MapEngine (ULONG) - Pointer to a mapping-engine.
  2105.                 This can greatly improve render performance.
  2106.                 Default - NULL.
  2107.                 
  2108.                 Notes:
  2109.                 - Mapping-engines are not applied for rendering
  2110.                   to HAM modes.
  2111.                 - With dithering enabled, you better do not
  2112.                   specify a mapping-engine which was created with
  2113.                   a link to a histogram. Accurate conversion could
  2114.                   not be guaranteed in this case.
  2115.  
  2116.    RESULTS
  2117.         success - returncode to indicate whether the operation
  2118.                   succeeded. You must at least check for
  2119.                   REND_SUCCESS.
  2120.  
  2121.    NOTES
  2122.         - This function may call the progress callback Hook with
  2123.           the PMSGTYPE_LINES_RENDERED message type.
  2124.  
  2125.    SEE ALSO
  2126.         MapRGBArrayA(), ConvertChunkyA(), CreateMapEngineA(),
  2127.         CreateScaleEngineA(), render/render.h, render/renderhooks.h
  2128.  
  2129.  
  2130. render.library/RGBArrayDiversityA           render.library/RGBArrayDiversityA
  2131.  
  2132.    NAME
  2133.         RGBArrayDiversityA - calculate RGB array adaptibility
  2134.         RGBArrayDiversity  - varargs stub for RGBArrayDiversityA
  2135.  
  2136.    SYNOPSIS
  2137.         diversity = RGBArrayDiversityA(rgbarray,width,height,taglist)
  2138.         d0                             a0       d0    d1     a1
  2139.  
  2140.         LONG RGBArrayDiversityA(ULONG *,UWORD,UWORD,struct TagItem *)
  2141.  
  2142.         LONG RGBArrayDiversity(ULONG *,UWORD,UWORD,tag,...,TAG_DONE)
  2143.  
  2144.    FUNCTION
  2145.         This function calculates a RGB array's adaptibility to a palette
  2146.         or mapping-engine.
  2147.  
  2148.    INPUTS
  2149.         rgbarray - pointer to an array of RGB data
  2150.         width    - width of the RGB array [pixels]
  2151.         height   - height of the RGB array [pixels]
  2152.         taglist  - pointer to an array of tagitems
  2153.  
  2154.    TAGS
  2155.         RND_Palette (ULONG) - pointer to a palette. Either this or the
  2156.                 RND_MapEngine argument is obligatory!
  2157.  
  2158.         RND_MapEngine (ULONG) - pointer to a mapping-engine. Either this
  2159.                 or the RND_Palette argument is obligatory!
  2160.  
  2161.         RND_SourceWidth (UWORD) - Total width of the RGB array [pixels].
  2162.                 Default - equals to the specified width.
  2163.  
  2164.         RND_Interleave (ULONG) - number of pixels to skip horizontally.
  2165.                 Default - 0.
  2166.  
  2167.    RESULTS
  2168.         diversity - an indicator for the RGB array's adaptibility to
  2169.                     the given palette or mapping-engine. 0 indicates
  2170.                     perfect adaptibility, 195075 indicates the worst
  2171.                     case.
  2172.  
  2173.    IMPLEMENTATION   
  2174.         Every RGB in the source array is adapted to the specified
  2175.         palette or mapping-engine. Now assume p2 is the RGB of the
  2176.         palette entry that matches best with the requested RGB p1.
  2177.  
  2178.             R
  2179.             |
  2180.             |      * p2
  2181.             |     /
  2182.             |    /
  2183.             |   / d
  2184.             |__/_________G
  2185.            /  /
  2186.           /  * p1
  2187.          /
  2188.         B
  2189.  
  2190.         This function sums up the diversity d² for every RGB in the
  2191.         source array, and divides it by the number of pixels processed:
  2192.  
  2193.                           k=pixels
  2194.                   1         ___
  2195.         D   =   ------   .  \\  `   d(k)²
  2196.                 pixels      /__,
  2197.  
  2198.                              k=1
  2199.  
  2200.         D is returned, so what you get is the average d² for all RGB
  2201.         values that appear in the array. d² is summed up instead of d
  2202.         because it is a better indicator for most purposes.
  2203.  
  2204.         Best case - all pixels match perfectly: D(min) = 0.
  2205.         Worst case - all pixels are white, and the only available color
  2206.         in the palette is black: D(max) = 255²+255²+255² = 195075.
  2207.         
  2208.    EXAMPLE        
  2209.         D indicates a palette's applicability for the given RGB array.
  2210.         You can e.g. use it to decide whether error diffusion should be
  2211.         enabled or not.
  2212.  
  2213.         dithermode = DITHERMODE_NONE;
  2214.  
  2215.         D = RGBArrayDiversity(rgbarray, width, height, 
  2216.             RND_Palette, destpalette, RND_Interleave, 4, TAG_DONE);
  2217.  
  2218.         if (D > threshold)
  2219.         {
  2220.             dithermode = DITHERMODE_FS;
  2221.         }
  2222.  
  2223.         Render(rgbarray, width, height, chunkyarray, destpalette,
  2224.             RND_DitherMode, dithermode, TAG_DONE);
  2225.  
  2226.         The interleave factor increases speed drastically. Nonetheless,
  2227.         RGBArrayDiversity() is yet very fast. You gain a lot of
  2228.         performance if only dithering can be avoided sometimes.
  2229.  
  2230.         Applying RGBArrayDiversity() to a mapping-engine is even more
  2231.         sophisticated. Use this if a histogram is available for the RGB
  2232.         array.
  2233.  
  2234.         me = CreateMapEngine(palette,RND_Histogram,histo,TAG_DONE);
  2235.  
  2236.         D = RGBArrayDiversity(rgbarray, width, height, 
  2237.             RND_MapEngine, me, RND_Interleave, 4, TAG_DONE);
  2238.  
  2239.         if (D > threshold)
  2240.         {
  2241.             Render(rgbarray, width, height, chunkyarray, destpalette,
  2242.                 RND_DitherMode, DITHERMODE_FS, TAG_DONE);
  2243.         }
  2244.         else
  2245.         {
  2246.             MapRGBArray(me, rgbarray, width, height, chunkyarray, NULL);
  2247.         }
  2248.  
  2249.         This example provides even higher performance. MapRGBArrayA() is
  2250.         faster than RenderA(), especially when the mapping-engine is
  2251.         coupled with a histogram. Note: That mapping-engine's histogram
  2252.         has to be of a HSTYPE_..._TURBO type with the same resolution as
  2253.         the palette.
  2254.  
  2255.    SEE ALSO
  2256.         ChunkyArrayDiversityA()
  2257.  
  2258.  
  2259. render.library/ScaleA                                   render.library/ScaleA
  2260.  
  2261.    NAME
  2262.         ScaleA - scale an image.
  2263.         Scale  - varargs stub for ScaleA.
  2264.  
  2265.    SYNOPSIS
  2266.         success = ScaleA(engine,source,dest,taglist)
  2267.                          a0     a1     a2   a3
  2268.         
  2269.         ULONG ScaleA(APTR,APTR,APTR,struct TagItem *)
  2270.         
  2271.         ULONG Scale(APTR,APTR,APTR,tag,...,TAG_DONE)
  2272.  
  2273.    FUNCTION
  2274.         This function scales a source array of pixels to another
  2275.         array.
  2276.  
  2277.    INPUTS
  2278.         engine  - pointer to a scaling-engine created
  2279.                   with CreateScaleEngineA()
  2280.         source  - pointer to source array of pixels
  2281.         dest    - pointer to destination array
  2282.         taglist - pointer to an array of TagItems
  2283.  
  2284.    TAGS
  2285.         RND_SourceWidth (UWORD) - Total width of the source array [pixels].
  2286.                 Default - equals to the source width the scaling-engine
  2287.                           was created with.
  2288.  
  2289.         RND_DestWidth (UWORD) - Total width of the dest array [pixels].
  2290.                 Default - equals to the destination width the
  2291.                           scaling-engine was created with.
  2292.  
  2293.         RND_LineHook (ULONG) - Pointer to a callback hook structure
  2294.                 for line-related operations during conversion. This
  2295.                 hook is executed once before a line is processed and
  2296.                 once after it has been completed. Refer to
  2297.                 render/renderhooks.h for further information.
  2298.                 Default - NULL.
  2299.  
  2300.    RESULTS
  2301.         success - CONV_SUCCESS to indicate that the operation
  2302.                   succeeded. Currently, the only reason for this
  2303.                   function to fail is CONV_CALLBACK_ABORTED.
  2304.  
  2305.    NOTES
  2306.         - It is possible to downscale (shrink) an array over itself,
  2307.           i.e. source and destination buffers may be the same in this
  2308.           case.
  2309.  
  2310.    SEE ALSO
  2311.         CreateScaleEngineA(), RenderA(), ConvertChunkyA()
  2312.  
  2313.  
  2314. render.library/ScaleOrdinate                     render.library/ScaleOrdinate
  2315.  
  2316.    NAME
  2317.         ScaleOrdinate - scale a single ordinate.
  2318.  
  2319.    SYNOPSIS
  2320.         scaled_ordinate = ScaleOrdinate(start,dest,ordinate)
  2321.         d0                              d0    d1   d2
  2322.  
  2323.         UWORD ScaleOrdinate(UWORD,UWORD,UWORD)
  2324.  
  2325.    FUNCTION
  2326.         This function scales a single ordinate. The algorythm used here
  2327.         is identical to what scaling-engines are created with.
  2328.         
  2329.    INPUTS
  2330.         start    - original value (e.g. width or height)
  2331.                    e.g. the original width of an image.
  2332.                    This value usually corresponds to a
  2333.                    start value with CreateScaleEngineA().
  2334.                    Must not be 0.
  2335.         dest     - destination value (e.g. width or height)
  2336.                    e.g. the scaled width of an image.
  2337.                    This value usually corresponds to a
  2338.                    dest value with CreateScaleEngineA().
  2339.                    Must not be 0.
  2340.         ordinate - a single ordinate (e.g. of a pixel).
  2341.                    Must be less than <start>.
  2342.  
  2343.    RESULTS
  2344.         scaled_ordinate - the new ordinate (after scaling)
  2345.         
  2346.    EXAMPLE        
  2347.         Assume you have a specific pair of coordinates that represent a
  2348.         particular pixel inside an image. You can use this function to
  2349.         determine the pixel's new coordinates after the image has been
  2350.         scaled:
  2351.  
  2352.         new_pixel_x = ScaleOrdinate(picwidth,newwidth,pixel_x);
  2353.         new_pixel_y = ScaleOrdinate(picheight,newheight,pixel_y);
  2354.  
  2355.    SEE ALSO
  2356.         CreateScaleEngineA()
  2357.  
  2358.  
  2359. render.library/SortPaletteA                       render.library/SortPaletteA
  2360.  
  2361.    NAME
  2362.         SortPaletteA - sort a palette.
  2363.         SortPalette  - varargs stub for SortPaletteA.
  2364.  
  2365.    SYNOPSIS
  2366.         success = SortPaletteA(palette,mode,taglist)
  2367.         d0                     a0      d0   a1
  2368.         
  2369.         ULONG SortPaletteA(APTR,ULONG,struct TagItem *)
  2370.         
  2371.         ULONG SortPalette(APTR,ULONG,tag,...,TAG_DONE)
  2372.  
  2373.    FUNCTION
  2374.         Sorts a palette according to a sort mode. Some sort modes apply
  2375.         to palettes solely, some others additionally require a
  2376.         histogram.
  2377.  
  2378.    INPUTS
  2379.         palette - pointer to a palette created
  2380.                   with CreatePaletteA().
  2381.  
  2382.         mode    - sort mode. Currently defined are:
  2383.  
  2384.                   PALMODE_BRIGHTNESS      - sort the palette entries
  2385.                                 by brightness.
  2386.  
  2387.                   PALMODE_SATURATION      - sort the palette entries
  2388.                                 by their color intensity.
  2389.  
  2390.                   PALMODE_POPULARITY      - sort the palette entries
  2391.                                 by the number of pixels that they
  2392.                                 represent. You must specify the
  2393.                                 RND_Histogram taglist argument.
  2394.  
  2395.                   PALMODE_REPRESENTATION  - sort the palette entries
  2396.                                 by the number of histogram entries
  2397.                                 that they represent. You must specify
  2398.                                 the RND_Histogram taglist argument.
  2399.                   
  2400.                   PALMODE_SIGNIFICANCE    - sort the palette entries
  2401.                                 by their optical significance for the
  2402.                                 human eye. Implementation is unknown
  2403.                                 to you and may change. You must supply
  2404.                                 the RND_Histogram taglist argument.
  2405.  
  2406.                   PALMODE_ASCENDING       - by default, sort direction
  2407.                                 is descending, i.e. precedence is
  2408.                                 `more-to-less' of the given effect.
  2409.                                 Combine with this flag to invert the
  2410.                                 sort direction.
  2411.  
  2412.         taglist - pointer to an array of tagitems.
  2413.  
  2414.    TAGS
  2415.         RND_Histogram (ULONG) - pointer to a histogram. This taglist
  2416.                argument is obligatory for some sort modes. (See above)
  2417.  
  2418.    RESULTS
  2419.         success - return value to indicate whether the operation succeeded.
  2420.                   You must at least check for SORTP_SUCCESS.
  2421.  
  2422.    NOTES
  2423.         SortPaletteA() can be extremely useful when a palette is to be
  2424.         allocated from a ColorMap via ObtainBestPenA(). After sorting
  2425.         with PALMODE_SIGNIFICANCE, important colors will be treated
  2426.         first. This increases probability for ObtainBestPenA() to
  2427.         allocate new pens for the most significant entries in the
  2428.         palette.
  2429.  
  2430.  
  2431. render.library/TintRGBArrayA                     render.library/TintRGBArrayA
  2432.  
  2433.    NAME
  2434.         TintRGBArrayA - tint an RGB array.
  2435.         TintRGBArray  - varargs stub for TintRGBArrayA.
  2436.  
  2437.    SYNOPSIS
  2438.         TintRGBArrayA(sourcearray,width,height,RGB,ratio,destarray,tags)
  2439.                       a0          d0    d1     d2  d3    a1        a2
  2440.  
  2441.         void TintRGBArrayA(ULONG *,UWORD,UWORD,ULONG,UWORD,ULONG *,
  2442.                            struct TagItem *)
  2443.  
  2444.         void TintRGBArray(ULONG *,UWORD,UWORD,ULONG,UWORD,ULONG *,
  2445.                           tag,...,TAG_DONE)
  2446.  
  2447.    FUNCTION
  2448.         This function mixes an RGB array with the specified RGB
  2449.         value and a mixing ratio. The result is written to another
  2450.         array, which may be the same as the source array.
  2451.  
  2452.    INPUTS
  2453.         sourcearray         - pointer to an ARGB array
  2454.         width               - width [pixels]
  2455.         height              - height [rows]
  2456.         RGB                 - tint RGB
  2457.         ratio               - tint ratio (0...255)
  2458.         destarray           - pointer to an ARGB array
  2459.         taglist             - pointer to an array of TagItems
  2460.  
  2461.    TAGS
  2462.         RND_SourceWidth (UWORD) - Total width of the source array [pixels].
  2463.                 Default - equals to the specified width.
  2464.  
  2465.         RND_DestWidth (UWORD) - Total width of the dest array [pixels].
  2466.                 Default - equals to the specified width.
  2467.  
  2468.    RESULTS
  2469.         none
  2470.  
  2471.  
  2472.